---
title: Обновление до Astro v4
description: Как обновить ваш проект до последней версии Astro (v4.0).
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

Это руководство поможет вам перейти с Astro v3 на Astro v4.

Вам нужно обновить старый проект до v3? Смотрите наше руководство по миграции [старых проектов](/ru/guides/upgrade-to/v3/).

Нужно посмотреть документацию по v3? Посетите этот сайт [старая версия документации (не поддерживаемый снимок v3.6)](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/).

## Обновление Astro

Обновите версию Astro и всех официальных интеграций вашего проекта до последних версий с помощью менеджера пакетов.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Обновление Astro и официальных интеграций
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Обновление Astro и официальных интеграций
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Обновление Astro и официальных интеграций
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

Вы также можете [обновить свои интеграции Astro вручную](/ru/guides/integrations-guide/#обновление-вручную), если это необходимо, и вам также может понадобиться обновить другие зависимости в вашем проекте.

:::note[Следует ли продолжать читать?]
После обновления Astro до последней версии вам может не потребоваться вносить какие-либо изменения в ваш проект!

Но если вы заметите ошибки или неожиданное поведение, пожалуйста, проверьте ниже, что изменилось и что может потребовать обновления в вашем проекте.
:::

Astro v4.0 включает [потенциально разрушающие изменения](#разрушающие-изменения), а также [удаление некоторых ранее устаревших функций](#ранее-устаревшие-функции-теперь-удалены). 

Если после обновления до версии 4.0 ваш проект работает не так, как ожидалось, ознакомьтесь с этим руководством, чтобы получить обзор всех изменений и инструкции по обновлению вашей кодовой базы.

Полную информацию о выпуске смотрите в [журнале изменений](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md).

## Удалены экспериментальные флаги Astro v4.0

Удалите экспериментальный флаг `devOverlay` и переместите любую конфигурацию `i18n` на верхний уровень в `astro.config.mjs`:

```js del={5-9} ins={11-14} title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})
```

Эти конфигурации, `i18n` и переименованная `devToolbar`, теперь доступны в Astro v4.0.

Подробнее об этих двух интересных функциях и многом другом читайте в [посте v4.0 в Блоге](https://astro.build/blog/astro-4/)!

## Обновления

Любые крупные обновления зависимостей Astro могут привести к изменениям в вашем проекте.

### Обновлено: Vite 5.0

В Astro v3.0 Vite 4 использовался в качестве сервера разработки и производственного бандлера.

Astro v4.0 переходит с Vite 4 на Vite 5.

#### Что делать?

Если вы используете специфические для Vite плагины, конфигурации или API, проверьте [руководство по миграции Vite](https://vitejs.dev/guide/migration) на наличие изменений и обновите свой проект при необходимости. В самом Astro никаких изменений нет.

### Обновлено: зависимости unified, remark и rehype

В Astro v3.x для обработки Markdown и MDX использовался unified v10 и связанные с ним совместимые пакеты remark/rehype.

Astro v4.0 обновляет [unified до v11](https://github.com/unifiedjs/unified/releases/tag/11.0.0) и другие пакеты remark/rehype до последней версии.

#### Что делать?

Если вы использовали пользовательские пакеты remark/rehype, обновите их до последней версии с помощью менеджера пакетов, чтобы убедиться, что они поддерживают unified v11. Используемые вами пакеты можно найти в файле `astro.config.mjs`.

При использовании активно обновляемых пакетов не должно произойти никаких существенных изменений, но некоторые пакеты могут быть еще не совместимы с unified v11.
Перед развертыванием визуально проверьте свои Markdown/MDX-страницы, чтобы убедиться, что ваш сайт работает так, как нужно.

## Разрушающие изменения

Следующие изменения считаются разрушающими изменениями в Astro. Разрушающие изменения могут обеспечивать или не обеспечивать временную обратную совместимость, и вся документация обновляется, чтобы ссылаться только на текущий, поддерживаемый код.

Если вам нужно обратиться к документации по проекту v3.x, вы можете просмотреть этот [(не поддерживаемый) снимок документации до выхода v4.0](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/).

### Переименовано: `entrypoint` (API интеграций)

В Astro v3.x свойство API интеграций `injectRoute`, указывающее точку входа в маршрут, называлось `entryPoint`.

В Astro v4.0 это свойство переименовано в `entrypoint`, чтобы соответствовать другим API Astro. Свойство `entryPoint` устарело, но будет продолжать работать и выводить в журнал предупреждение с предложением обновить код.

#### Что мне делать?

Если у вас есть интеграции, использующие API `injectRoute`, переименуйте свойство `entryPoint` в `entrypoint`. Если вы автор библиотеки, которая хочет поддерживать и Astro 3, и Astro 4, вы можете указать и `entryPoint`, и `entrypoint`, и в этом случае предупреждение не будет регистрироваться.

```js ins={4} del={3}
injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});
```

### Изменено: сигнатура `app.render` в API интеграций

В Astro v3.0 метод `app.render()` принимал `routeData` и `locals` как отдельные, необязательные аргументы. 

В версии Astro v4.0 сигнатура метода `app.render()` была изменена. Теперь эти два свойства доступны в одном объекте. Объект и эти два свойства по-прежнему необязательны.

#### Что делать?

Если вы поддерживаете адаптер, текущая сигнатура будет работать до следующей основной версии. Чтобы перейти на новую сигнатуру, передавайте `routeData` и `locals` как свойства объекта, а не как несколько независимых аргументов.

```diff lang="js"
- app.render(request, routeData, locals)
+ app.render(request, { routeData, locals })
```
### Изменено: адаптеры теперь должны указывать поддерживаемые функции

В Astro v3.x от адаптеров не требовалось указывать поддерживаемые ими функции.

Astro v4.0 требует, чтобы адаптеры передавали свойство `supportedAstroFeatures{}` для указания списка поддерживаемых ими функций. Это свойство больше не является необязательным.

#### Что мне делать?

Авторам адаптеров необходимо передавать свойство `supportedAstroFeatures{}`, чтобы указать список поддерживаемых ими функций.

```js title="my-adapter.mjs" ins={9-11}
export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}
```

### Удалено: свойство `path` языка Shiki

В Astro v3.x язык Shiki, переданный в `markdown.shikiConfig.langs`, автоматически преобразовывался в язык, совместимый с Shikiji. Shikiji - это внутренний инструментарий, используемый Astro для подсветки синтаксиса.

В Astro v4.0 удалена поддержка свойства `path` для языка Shiki, которое вызывало путаницу при настройке. Оно заменено импортом, который может быть передан в `langs` напрямую.

#### Что делать?

Вместо этого следует импортировать JSON-файл языка и передать его в опцию.

```diff lang="js"
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: '../../custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

## Утратило актуальность

Следующие устаревшие функции больше не поддерживаются и не документируются. Пожалуйста, обновите свой проект соответствующим образом.

Некоторые устаревшие функции могут временно продолжать работать, пока не будут полностью удалены. Другие могут не иметь никакого эффекта или выдавать ошибку, побуждающую вас обновить код.

### Утратило актуальность: `handleForms` для событий `submit` Анимаций Переходов

В Astro v3.x проекты, использующие компонент `<ViewTransitions />`, должны были отказаться от обработки событий `submit` для элементов `form`. Это делалось путем передачи свойства `handleForms`.

Astro v4.0 обрабатывает события `submit` для элементов `form` по умолчанию, когда используются `<ViewTransitions />`. Свойство `handleForms` было устаревшим и больше не имеет никакого значения.

#### Что делать?

Удалите свойство `handleForms` из компонента `ViewTransitions`. В нем больше нет необходимости.

```astro title="src/pages/index.astro" del="handleForms"
---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- здесь всякие штуки -->
  </body>
</html>
```

Чтобы отказаться от обработки события `submit`, добавьте атрибут `data-astro-reload` к соответствующим элементам `form`.

```astro title="src/components/Form.astro" ins="data-astro-reload"
<form action="/contact" data-astro-reload>
  <!-- -->
</form>
```

## Ранее устаревшие функции теперь удалены

Следующие устаревшие функции были полностью удалены из кодовой базы и больше не могут быть использованы. Некоторые из этих функций могли продолжать работать в вашем проекте даже после удаления. Другие могли не иметь никакого эффекта.

Проекты, содержащие эти удаленные функции, не смогут быть собраны, и больше не будет никакой сопроводительной документации с рекомендациями по удалению этих функций.

### Удалено: возврат простых объектов из конечных точек

В Astro v3.x возврат простых объектов из конечных точек был устаревшим, но все еще поддерживался для сохранения совместимости с Astro v2. Для облегчения перехода была также предоставлена утилита `ResponseWithEncoding`.

В Astro v4.0 поддержка простых объектов удалена, и конечные точки должны всегда возвращать `Response`. Утилита `ResponseWithEncoding` также удалена в пользу правильного типа `Response`.

#### Что делать?

Обновите свои конечные точки, чтобы они возвращали объект `Response` напрямую.

```diff lang="ts"
  export async function GET() {
-   return { body: { "title": "Bob's blog" }};
+   return new Response(JSON.stringify({ "title": "Bob's blog" }));
  }
```

Чтобы отказаться от использования `ResponseWithEncoding`, переделайте ваш код для использования `ArrayBuffer` вместо этого:

```diff lang="ts"
  export async function GET() {
    const file = await fs.readFile('./bob.png');
-   return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
+   return new Response(file.buffer);
  }
```

### Удалено: `build.split` и `build.excludeMiddleware`

В Astro v3.0 опции конфигурации сборки `build.split` и `build.excludeMiddleware` были устаревшими и заменены на [опции конфигурации адаптера](/ru/reference/adapter-reference/#adapter-features) для выполнения тех же задач.

В Astro v4.0 эти свойства полностью удалены.

#### Что делать?

Если вы используете устаревшие свойства `build.split` или `build.excludeMiddleware`, вам необходимо удалить их, так как они больше не существуют.

См. руководство по переходу на v3 для [обновления этих устаревших свойств промежуточного ПО](/ru/guides/upgrade-to/v3/#утратило-актуальность-buildexcludemiddleware-и-buildsplit) с конфигурациями адаптеров.

### Удалено: `Astro.request.params`

В Astro v3.0 API `Astro.request.params` был устаревшим, но сохранен для обратной совместимости.

В Astro v4.0 эта опция полностью удалена.

#### Что делать?

Обновите все упоминания на [`Astro.params`](/ru/reference/api-reference/#astroparams), который является поддерживаемой заменой.

```astro del={1} ins={2}
const { id } = Astro.request.params;
const { id } = Astro.params;
```

### Удалено: `markdown.drafts`

В Astro v3.0 использование `markdown.drafts` для управления созданием черновиков постов было устаревшим.

В Astro v4.0 эта опция полностью удалена.

#### Что делать?

Если вы использовали устаревшую опцию `markdown.drafts`, то теперь вы должны удалить ее, так как она больше не существует.

Чтобы продолжать помечать некоторые страницы в проекте как черновики, используйте [миграцию в коллекции контента](/ru/guides/content-collections/#migrating-from-file-based-routing) и [ручную фильтрацию страниц](/ru/guides/content-collections/#filtering-collection-queries) со свойством `draft: true` frontmatter вместо этого.

### Удалено: `getHeaders()`

В Astro v3.0 экспорт `getHeaders()` в Markdown был устаревшим и заменен на `getHeadings()`.

В Astro v4.0 эта опция полностью удалена.

#### Что делать?

Если вы используете устаревшую опцию `getHeaders()`, вы должны удалить ее, так как она больше не существует. Замените все его экземпляры на `getHeadings()`, который является поддерживаемой заменой.

```js del={2} ins={3}
const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();
```

### Удалено: использование `rss` в `getStaticPaths()`

В Astro v3.0 использование устаревшего помощника `rss` в `getStaticPaths()` приводило к ошибке.

В Astro v4.0 этот помощник полностью удален.

#### Что делать?

Если вы используете неподдерживаемый метод генерации RSS-каналов, теперь вы должны использовать интеграцию [`@astrojs/rss`](/ru/guides/rss/) для полной настройки RSS.

### Удалено: имена HTTP-методов в нижнем регистре

В Astro v3.0 использование имен методов HTTP-запросов в нижнем регистре (`get`, `post`, `put`, `all`, `del`) было устаревшим.

В Astro v4.0 поддержка строчных имен полностью удалена. Все методы HTTP-запросов теперь должны быть написаны в верхнем регистре.

#### Что делать?

Если вы используете устаревшие имена в нижнем регистре, теперь вы должны заменить их на эквиваленты в верхнем регистре.

Обратитесь к руководству по миграции на v3 [для руководства по использованию методов HTTP-запросов в верхнем регистре](/ru/guides/upgrade-to/v3/#изменено-регистр-методов-http-запросов).

### Удалено: 301 редирект при отсутствии префикса `base`

В Astro v3.x сервер предпросмотра Astro возвращал 301 перенаправление при доступе к ресурсам из публичной директории без пути base.

В Astro v4.0, когда сервер предпросмотра запущен, при доступе к ресурсам из публичной директории без префикса пути base возвращается статус 404, соответствующий поведению сервера разработки.
 
#### Что делать?

При использовании сервера предварительного просмотра Astro все импортируемые статические активы и URL-адреса из публичной директории должны иметь префикс [значения base](/ru/reference/configuration-reference/#base) к пути.

В следующем примере показан атрибут `src`, необходимый для отображения изображения из публичной папки, когда `base: '/docs'` настроен:

```astro title="src/pages/index.astro" ins="/docs"
// Для доступа к public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">.
```

### Удалено: автоконверсия `astro/client-image`

В Astro v3.x тип `astro/client-image` (используемый для устаревшей интеграции изображений) был удален, но автоматически преобразовывался в стандартный тип Astro `astro/client`, если был найден в вашем файле `env.d.ts`.

Astro v4.0 игнорирует `astro/client-image` и больше не будет обновлять `env.d.ts` для вас автоматически.

#### Что делать?

Если у вас были настроены типы для `@astrojs/image` в `src/env.d.ts` и обновление до v3.0 не привело к автоматическому преобразованию типов, замените тип `astro/client-image` вручную на `astro/client`.

```ts title="src/env.d.ts" del={1} ins={2}
  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />
```

## Ресурсы сообщества

Знаете хороший ресурс по Astro v4.0? [Отредактируйте эту страницу](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) и добавьте ссылку ниже!

## Известные проблемы

Пожалуйста, проверьте [Проблемы Astro на GitHub](https://github.com/withastro/astro/issues/), чтобы узнать о любых известных проблемах, или чтобы создать проблему самостоятельно.